Night Owl 6

home *** CD-ROM | disk | FTP | other *** search

/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 038a / qbcmnt11.zip / COMMENTS.DOC < prev next >

Wrap

Text File | 1991-02-26 | 49KB | 844 lines

┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ COMMENTS - Version 1.1 ││ ││ ││ ││ (c) 1991 by LAMCO Software ││ ││ ││ ││ The program that will add comments for ││ ││ you in any of your QuickBASIC listings ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ What is COMMENTS ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ Any serious reference manual about programming in any language says at least once that every programmer should use comments extensively. Let's face it, that's the part of writting a program that everybody hates the most. COMMENTS takes care of a great part of that burden for you by adding to your listing all the information it can gather from analyzing it. COMMENTS makes a backup copy of your listing in a file that uses the same filename with a .BAK extension. It also creates a separate file with a .STR extension that will contain the complete structure of your listing if there is at least one procedure. The new file with a .BAS extension will contain your listing and the following : In the Main Module section : For each procedure : - Name and type - Name and type - Name of the module (file) - Description - Language used - Parameters - Source of the program - All the variables used - Description - Module level declarations - Requirements - CONST statements - Command line parameters - TYPE structures - Files listed in .MAK file - DECLARE FUNCTION - All the variables used - DECLARE SUB COMMENTS doesn't modify your listing in any way. Everything that is added to your listing by COMMENTS is written inside a box that is added at the very beginning of the file or over the first line of a procedure (SUB or FUNCTION). ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ What is added to the module level of your listing ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ There is one box for each kind of information that COMMENTS can gather from your listing. The boxes added to the module level will be : 1 - The MAIN box that will contain the Name, Type, Module name, Language, and Source of your listing. 2 - The DESCRIPTION box contains the description of your program. You must of course type in that description. 3 - The REQUIREMENTS box. This box will list all that is required by your program to work properly, that may be for example a CGA or VGA monitor, or a special Quick Library, or a particular version of DOS. Anything that is required by your program will be listed here. 4 - The .MAK file box. If you use a .MAK file with your program, the files listed in that .MAK file will be listed in that box. 5 - The COMMAND LINE PARAMETERS box. If when compiled your program requires or allows command line parameters, COMMENTS will prompt you to type in the different parameters that are allowed along with a short description. You should also write a line describing the syntax of the command. Everything you will type in when prompted will be enclosed in this box. 6 - The VARIABLES box. This box will contain a list of all the different variables and arrays that are used in the module level of your program. Each variable and array is listed on a separate line so the next time you load your listing in the QuickBASIC editing environment, you may add a short description for each of these variables and arrays. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ What is added to each procedure of your listing ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ 1 - The NAME box which tells the name of the procedure and whether it is a subprogram or a function. 2 - The DESCRIPTION box contains the description of the procedure. COMMENTS prompts you to type it in whenever a new procedure is analyzed. 3 - The PARAMETERS box. If any variables, arrays, or TYPE structures are passed to a procedure through parameters, COMMENTS will identify them and list them in this box, one to a line, so you may later add a description to each of them. 4 - The VARIABLES box. Same as in the module level section, but contains, of course only the variables and arrays used within the concerned procedure. 5 - Finally, the MODULE LEVEL DECLARATIONS box. This box contains each declaration that must be made in the module level section of your listing for the concerned procedure to work properly, except for DIM statements. This means that if a TYPE structure is used in the procedure, the TYPE declaration that is required in the module level will be written in that box. If a constant is used, a CONST declaration will be written. And a DECLARE SUB or DECLARE FUNCTION declaration will be written in that box for each procedure that is called from within the procedure. If you should eventually copy the procedure to another of your listings, you can find out immediately by looking at this box what are the declarations that you must add to the module level of this new listing for that procedure to work properly. As for the DIM statements, look in the PARAMETERS and VARIABLES boxes to find the arrays used, and then add the propper DIM statements in the module level or REDIM statements in the procedure itself. Note : All these boxes are added to your listing, whether they are required or not. For example, if you do not use any variables in a given procedure, the VARIABLES box for that procedure will contain a single line saying "(none)". You may remove these unnecessary boxes if you wish, but they may be useful since looking at the beginning of a procedure tells you immediately what is in there and what is not. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ Requirements ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ In order for COMMENTS to work properly, your listings must be written in a certain way, but as you'll see, you probably already follow these conventions. 1 - The last line of the module level of your listing must be an "END" statement alone on one line. If you use more than one "END" statement, replace all of them except the last one by "SYSTEM", or use another QuickBASIC statement on the same line. For example, if you make a test that uses an "END" statement, as in the following case, IF Level% = 5 THEN END ELSE Level% = Level% + 1 END IF You can write the same test in any of the following ways : 1 - IF Level% = 5 THEN END ELSE Level% = Level% + 1 2 - IF Level% = 5 THEN CLS : END ELSE Level% = Level% + 1 END IF 3 - IF Level% = 5 THEN Note : CLS has no effect END : CLS since the program ELSE will end before Level% = Level% + 1 reaching it END IF The trick is simply not to write any "END" statement that is not the last one alone on one line, and whatever is on that line must not be a remark or a string within doublequotes. 2 - All Variables, Arrays, Constants, TYPE Structures, Subprograms names, Functions names, and Parameters as well as COMMAND LINE Parameters, if any, must contain at least one lowercase letter. COMMENTS compares each string in your listing with its uppercase equivalent. This goes much faster than comparing it against every QuickBASIC reserved word, but requires the use of lowercase letters. 3 - If you use labels before DATA statements at the beginning of the module level part of your program, you should write them all in uppercase. Otherwise, COMMENTS will list them as variables. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ Requirements (part 2) ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ On the other hand, if you use labels after the "END" statement in error-handling routines, you must slightly modify your listing in the following way : DO NOT write an "END" statement before the error-handling routines, but DO write one after the routines. Then run COMMENTS. Afterwards, load your program into QuickBASIC, remove the "END" statement that is after the error-handling routines and add an "END" statement before the routines. If you don't modify your program in this way, COMMENTS will either generate an error message and terminate or it won't copy the error-handling routines in the new version of your listing. As for everything else, you may write your program in any way that is acceptable to QuickBASIC. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ How COMMENTS works ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ COMMENTS opens the file you have selected and then reads each line one by one. Each time a line is read, it is copied to a backup file. Then remarks and strings within doublequotes are removed from that line. All characters that are not numbers or letters are removed and each string left is then analyzed. Statements such as CONST or DIM tell COMMENTS what the following strings are. Every important string found is stored in memory and when the whole file as been read and backed up, your original file is closed and reopened. The file is then read again, only this time each line is copied to a temporary file with the same name as your listing but with a .TMP extension. As the file is read again, each string found that does not match its uppercase equivalent is compared to the strings in memory and stored according to what it is. This is why it is important that each variable, SubProgram name, and so forth, contain at least one lowercase letter. The other way around would have been to compare each string found with every QuickBASIC reserved word, which would take much more time. Once the end of the module level is reached, the .TMP file is closed and a new file with a .NEW extension is opened. All the module level boxes containing the appropriate information are written to this file and the .TMP file that now contains the module level part of your original listing without any modification is then copied to the .NEW file. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ How COMMENTS works (part 2) ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ The temporary file is then deleted and a new temporary file is opened. COMMENTS then reads the lines of the original file until the beginning of the first procedure. Then each new line read is copied to the temporary file while the listing is again analyzed. Once the end of the first procedure is reached, the appropriate information and the temporary file are added to the .NEW file and this process is repeated until the whole listing has been analyzed. Note : Anything that you write in your listing after the "END" statement or above the "SUB" or "FUNCTION" statement in any procedure won't be copied to the temporary file and therefore will not appear in the final file. This allows you to write temporary remarks that you don't want in the final version of your program. This is also the reason why you should merge or copy any 'INCLUDE$ file after the "END" statement of the module level. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ About '$INCLUDE files and .MAK files ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ COMMENTS is intended to be used with programs that use a single module. You can, however, use it with programs that use an '$INCLUDE file or with programs that use more than one module. - If your listing requires an '$INCLUDE file, merge or copy it in your original listing after the "END" statement of the module level before saving your listing. The merged '$INCLUDE file will not appear in the new version of your listing if you have merged it after the "END" statement. On the other hand, if you do not merge it, COMMENTS won't be able to identify the Constants, TYPE structures, and procedures. Therefore, everything will be listed as variables. - If you use more than one module, process them one by one. If you use an '$INCLUDE file, merge it in each module. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ How to use COMMENTS ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ Write your program as you would usually do, but make sure you follow the requirements stated earlier in this document. Don't write any remark you want to be in your program after the "END" statement of the module level or above the "SUB " or "FUNCTION" statement of any procedure. Once your program is completed, save it in ASCII format and exit QuickBASIC. Then call COMMENTS from the directory where your program is. If COMMENTS is in a subdirectory that appears in the PATH statement of your AUTOEXEC.BAT file, simply type COMMENTS on the command line and press [ENTER], otherwise, also type the path to the subdirectory where COMMENTS is. Select your program from the list of files that appear on screen and answer each question as you are prompted. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ How to use COMMENTS - Answering prompts ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔══════════════╗ ╔═══════════════════════════════════════════════════════╗ ║ ATTRIB .BAS ║ ║ ║ ║ BIN2HEX .BAS ║ ║ QuickBASIC comments adding utility ║ ║ BIOSCALL.BAS ║ ║ ║ ║ BITS .BAS ║ ║ Available to you through the Shareware concept ║ ║ BOXES .BAS ║ ║ ║ ║ CALENDAR.BAS ║ ║ Please read the accompanying documentation ║ ║ DOLLARS .BAS ║ ║ ║ ║ DOSCALLS.BAS ║ ╚═══════════════════════════════════════════════════════╝ ║ EDIT .BAS ║ ╔═══════════════════════════════════════════════════════╗ ║ ERROR .BAS ║ ║ ║ ║ FILEINFO.BAS ║ ║ Reading directory - Please wait ... ║ ║ GCURSOR .BAS ║ ║ ║ ║ HEX2BIN .BAS ║ ║ Please choose the file to add comments to. ║ ║ KEYS .BAS ║ ║ ║ ║ MOUSSUBS.BAS ║ ║ [HOME] [END] [PgUp] [PgDn] [Up and Down arrows] ║ ║ NEWBOXES.BAS ║ ║ ║ ║ PARSE .BAS ║ ║ [ENTER] to select - [ESC] to quit ║ ║ STRINGS .BAS ║ ║ ║ ╚══════════════╝ ╚═══════════════════════════════════════════════════════╝ Shown above is what appears on screen when COMMENTS is loaded. Only the files with a .BAS extension in the current directory will be listed and the first one will be highlighted. If there are no .BAS files in the current directory, COMMENTS will display an error message and exit. If there are more than 18 files with a .BAS extension in the current directory, use the cursor keys to highlight the listing you want to process and press [ENTER]. You may press [ESC] to exit the program. For example purposes, let's select BOXES.BAS and walk through COMMENTS to show you how it works. Note that for your convenience, both versions of BOXES.BAS are included with COMMENTS. This listing is not copyrighted and you are free to use it in your listings. BOXES.BAS is a toolbox that was written to draw different kinds of boxes on screen in different listings. BOXES.BAK is the original listing while BOXES.BAS is the new file written by COMMENTS. The descriptions that appear in the PARAMETERS and VARIABLES boxes were added after, not by COMMENTS. Once you have highlighted BOXES.BAS and pressed [ENTER], the following screen will appear : ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔═════════════════════════════╗ ╔═══════════════════════════════════════╗ ║ Making backup copy of ║ ║ Number of declared SubPrograms : 7 ║ ║ ║ ║ ║ ║ BOXES.BAS ║ ║ Number of declared Functions : 0 ║ ║ ║ ║ ║ ║ while reading it. ║ ║ Number of CONST statements : 0 ║ ║ ║ ║ ║ ║ Backup filename is ║ ║ Number of TYPE structures : 0 ║ ║ ║ ║ ║ ║ BOXES.BAK ║ ║ Number of SubPrograms found : 7 ║ ║ ║ ║ ║ ║ Please wait ... ║ ║ Number of Functions found : 0 ║ ║ ║ ║ ║ ║ ║ ║ Command line parameters ? : No ║ ║ ║ ║ ║ ║ ║ ║ .MAK file required ? : No ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚═════════════════════════════╝ ╚═══════════════════════════════════════╝ At the beginning, all numbers are set to 0 and the "Command line parameters ?" and ".MAK file required ?" lines are not displayed. Each time an important information is found, the corresponding number is updated and when the whole file has been analyzed, the "Command line parameters ?" and ".MAK file required ?" lines will be printed with the appropriate "Yes" or "No". You will then be prompted to press a key to continue. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Enter name of program : ║ ║ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ The above screen will then appear, with COMMENTS prompting you to enter the name of your program. Type the name of your listing in the highlighted box. Until you press [ENTER], [Up Arrow], or [Down Arrow], COMMENTS gives you WordStar-like editing capabilities. That is, you can use [INS] to toggle overwrite mode on and off, [HOME], [END], [^LEFT], [^RIGHT], [^Q] to erase the whole line, and [^Q-Y] to erase the end of the line from the cursor position. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Enter name of program : ║ ║ ║ ║ BOXES ║ ║ ║ ║ ║ ║ Select the Type of the program ╔═════════════╗ ║ ║ ║ Application ║ ║ ║ [Up and Down arrows] - Move cursor ║ Utility ║ ║ ║ ║ Toolbox ║ ║ ║ [ENTER] - Select ║ Demo ║ ║ ║ ║ Game ║ ║ ║ Enter type : ░░░░░░░░░░░░░░░░░░░░░░░ ║ Other ║ ║ ║ ╚═════════════╝ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ Once you have pressed [ENTER], [Up Arrow], or [Down Arrow], the screen will be modified in the way shown above except for the "Enter type :" line and highlighted box. This appears only if you select "Other". You can now select the type of your program by highlighting the appropriate description, using the [Up] or [Down] arrow. If the type of your program does not appear in the list, select "Other". If you do select "Other", you again have access to WordStar-like editing capabilities until you press [ENTER], [Up Arrow], or [Down Arrow]. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Enter name of program : ║ ║ ║ ║ BOXES ║ ║ ║ ║ ║ ║ Select the Type of the program ╔═════════════╗ ║ ║ ║ Application ║ ║ ║ [Up and Down arrows] - Move cursor ║ Utility ║ ║ ║ ║ Toolbox ║ ║ ║ [ENTER] - Select ║ Demo ║ ║ ║ ║ Game ║ ║ ║ ║ Other ║ ║ ║ ╚═════════════╝ ║ ║ ║ ║ Enter source of program : ║ ║ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ The next step is to type in the source of your program. In most cases, it is your name that you will type there but if the listing comes from a magazine or a book, or any other source, write the reference here. Remember the WordStar-like editing capabilities. They apply here as well. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Enter description of program ║ ║ ║ ║ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ Once you have entered the source of your listing, COMMENTS will prompt you for its description. The above screen will appear and you will again have access to editing capabilities. In this case, though, [ENTER], [Up Arrow], and [Down Arrow] move the cursor up or down one line. You must press [ESC] to exit from this highlighted box. Don't worry about exceeding the length of the lines, COMMENTS provides wrap-around capabilities. Note, however, that when you exit this box, COMMENTS will concatenate everything you have written into one line and will then break that line in as many lines as required to fit the text into the comment box that will be added to your listing, removing any double spaces in the process. Therefore, you may not include blank lines within the box while using COMMENTS, but you may do so when you later load the new version of your listing in QuickBASIC. If you want to see what the text will look like in its final version, move the cursor to the upper left corner of the highlighted box and press the [BACKSPACE] key. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔══════════════════════════════════════════════╗ ╔═══════════════════════╗ ║ Select the Requirements of the program ║ ║ (none) ║ ║ ║ ║ DOS 2.x ║ ║ [Up and Down arrows] - Move cursor ║ ║ DOS 3.x ║ ║ ║ ║ DOS 4.x ║ ║ [ENTER] - Select/Unselect ║ ║ CGA ║ ║ ║ ║ EGA ║ ║ [ESC] - Exit ║ ║ VGA or MCGA ║ ║ ║ ║ Mouse ║ ║ ║ ║ Mouse (optional) ║ ╚══════════════════════════════════════════════╝ ║ Modem ║ ╔══════════════════════════════════════════════╗ ║ Joystick ║ ║ ║ ║ Printer ║ ║ ║ ║ Other ║ ║ ║ ║ Other ║ ║ ║ ║ Other ║ ║ ║ ║ Other ║ ║ ║ ║ Other ║ ║ ║ ║ Other ║ ╚══════════════════════════════════════════════╝ ╚═══════════════════════╝ There are still two more things that only you can tell COMMENTS, the requirements of your program and the language you used to write it. But both are simple to do. Shown above is the screen that prompts you for the requirements of your program. Use the [Up] and [Down] arrows to select each of the requirements that apply to your program. When all the requirements have been selected, press [ESC] to exit. Every time you press [ENTER], the current selection that is highlighted will be marked. You remove a mark by pressing [ENTER] while highlighting a selection that is already marked. When you press [ESC], all requirements marked will be included in the requirements box added to your listing. If you need a requirement that is not written as an available selection, select any of the "Other" lines. COMMENTS will prompt you to type that requirement. Again, you have access to editing capabilities until you press [ENTER], [Up], or [Down] arrow. Should you notice too late that you've made a typing mistake, highlight the requirement line that contains the misspelled word, unselect it by pressing [ENTER], highlight another "Other" line, and type a new line. The "Other" lines are provided so you can add such remarks as '$INCLUDE files, special libraries, or anything else that is required by your program to work properly. Now, the language you used to write your program. Use the [Up] and [Down] arrows to highlight the version of QuickBASIC that you used or select "Other" if you used another BASIC language and press [ENTER]. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔══════════════════════════════════════════════╗ ╔═══════════════════════╗ ║ Select the Requirements of the program ║ ║ (none) ║ ║ ║ ║ DOS 2.x ║ ║ [Up and Down arrows] - Move cursor ║ ║ DOS 3.x ║ ║ ║ ║ DOS 4.x ║ ║ [ENTER] - Select/Unselect ║ ║ √ CGA ║ ║ ║ ║ EGA ║ ║ [ESC] - Exit ║ ║ VGA or MCGA ║ ║ ║ ║ Mouse ║ ║ ║ ║ Mouse (optional) ║ ╚══════════════════════════════════════════════╝ ║ Modem ║ ╔══════════════════════════════════════════════╗ ║ Joystick ║ ║ Select language used in the program ║ ║ Printer ║ ║ ║ ║ Other ║ ║ QuickBASIC V. 4.0 ║ ║ Other ║ ║ QuickBASIC V. 4.5 ║ ║ Other ║ ║ Other ║ ║ Other ║ ║ ║ ║ Other ║ ║ ║ ║ Other ║ ╚══════════════════════════════════════════════╝ ╚═══════════════════════╝ If your program uses Command Line Parameters, another screen will be displayed and COMMENTS will prompt you to enter the appropriate information. To allow you to write each parameter on a different line, the editing capabilities inside this box are the same as when editing only one line. Each time you press [ENTER], [Up], or [Down] arrow, the cursor moves to the next line and you can no longer edit the previous line. To exit from that box, press [ENTER] on a blank line. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Now processing : Module level ║ ║ ║ ║ Variables found : 0 Reading ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ Once all the necessary information has been entered, the next screen to appear will be as shown above. Remember that all these screens were saved while analyzing BOXES.BAS with COMMENTS. COMMENTS is now analyzing the module level section of the program. Each time a new variable (or array) is found, the appropriate number is displayed. When the "END" statement is reached, "Reading" is replaced by "Writing". COMMENTS then writes the appropriate boxes to the .NEW file and copies the temporary file after the boxes. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Now processing : SUBPROGRAM DoubleBorderBox ║ ║ ║ ║ Variables found : 1 Procedure # 1 of 7 Reading ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ COMMENTS then resumes reading the file and when it finds the first procedure, it will replace "Module level" by either "SUBPROGRAM" or "FUNCTION" and will display the name of the procedure it is reading. Again the number of variables found is shown. COMMENTS also tells how many procedures it will have to process and which is the one that is currently being read. When COMMENTS finds an "END SUB" or "END FUNCTION" statement, actually the end of the procedure it was reading, a message and a highlighted box will appear on screen and COMMENTS will prompt you for the description of that procedure. Once you've typed it, COMMENTS will resume its reading. ╔════════════════════════════════════════════════════════════════════════╗ ║ COMMENTS - Version 1.1 (c) 1991 - by LAMCO Software ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Now processing : SUBPROGRAM DoubleBorderBox ║ ║ ║ ║ Variables found : 1 Procedure # 1 of 7 Writing ║ ╚════════════════════════════════════════════════════════════════════════╝ ╔════════════════════════════════════════════════════════════════════════╗ ║ Enter description of procedure ║ ║ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ║ ║ ║ ╚════════════════════════════════════════════════════════════════════════╝ When prompted to type the description of a procedure, the editing capabilities are the same as when entering the description of the program itself. Exit by pressing [ESC]. When the last procedure has been processed, the original .BAS file will be deleted (Remember that a copy with a .BAK extension was made when the file was read the first time) and the .NEW file is renamed with a .BAS extension. COMMENTS will then display a message telling that it is writting the structure file and when this is completed, it will display another message telling you that the processing of your listing is completed and prompting you to press a key to exit the program. When your computer is back to the command line, you should load QuickBASIC, call your program and then add remarks in the overstrike mode for each of the variables and parameters that COMMENTS has identified in your program. If you wish, you may merge the structure file to the main module of your program since each line begins with an apostrophe and the whole file is written in the same format as the other information that was added to your listing. Note that you can use COMMENTS before the final version of your program is completed. This might prove useful to find where there is a misspelled variable since both versions of that variable will be added to your listing in the variables list. Remember though that COMMENTS will write new boxes when you run it again on the new listing with a .BAS extension. If you use COMMENTS on a version of your program that is not the final one, delete the .BAS file after you've looked at it and rename the .BAK file with a .BAS extension so you use again your original listing. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ COMMENTS Limitations ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ COMMENTS will display an error message and terminate if your listing exceeds these limits : 100 files with a .BAS extension in the current directory 25 files in a .MAK file 60 Constants 25 TYPE structures 40 variables in any TYPE structure 100 Subprograms 60 Functions 100 different arrays in the whole listing 100 variables and arrays used within any procedure COMMENTS will also terminate if there is no "END" statement at the end of the module level section of your listing. Note : When COMMENTS terminates because of a problem, it doesn't erase any file. Therefore you may find a ".BAK", ".TMP", or ".NEW" file in your directory. These files need not be deleted since COMMENTS will overwrite them the next time you use it for the same listing. Also note that the original file is renamed only when the whole process is completed. So should COMMENTS stop because of any problem, DO NOT erase the ".BAS" file and rename the ".BAK" file. The ".BAS" file is your original listing. The ".BAK" file is a copy of it, but if COMMENTS stopped before it had time to copy all the lines of your original listing, the ".BAK" file is not complete. If a problem occurs, note the error message and look at the ".BAK", ".TMP", and ".NEW" files. You will then easily find out why COMMENTS stopped. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ About Shareware ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ COMMENTS is distributed through the Shareware concept. You are therefore encouraged to make copies and give them to anyone who might use it. We would also greatly appreciate it if you help us make it available to more users by uploading it to any BBS you have access to. The registration fee for COMMENTS is $ 20.00. Anyone who sends $ 30.00 or more will receive Version 2 as soon as it is available. Please support the Shareware concept. If you use COMMENTS, send your registration fee to the following address: LAMCO Software P.O. Box 46 Postal Station P.A.T. Montreal, Quebec, Canada H1B 5K1 Please state the program name and the version number. Help us make a better product available to you. Send us your suggestions and please report any problem. COMMENTS was written with QuickBASIC version 4.5 and is intended to be used with either version 4.0 or 4.5 of QuickBASIC, but you may use it with other versions of QuickBASIC or other BASIC languages, as long as your listing was saved in ASCII format. If you use COMMENTS with another BASIC language and you find that COMMENTS doesn't work properly, please write to us, describing what happened. Maybe we can modify COMMENTS so Version 2 will accept the other BASIC languages as well or at least tell you how you could write your program so COMMENTS will work. ┌┬──────────────────────────────────────────────────────────────────────────┬┐ ││ What's coming up in version 2.0 ││ └┴──────────────────────────────────────────────────────────────────────────┴┘ When a .MAK file is used, Version 2 will be able to process all the modules and read the '$INCLUDE files. The Structure file will also indicate in which module is each procedure called. Comments added to your listing will be updated rather than overwritten, so you won't have to type in the same information twice or more if you run COMMENTS more than once for the same listing. Version 2 will also include configuration possibilities, so you can set the colors and type in only once options that you use often in your listings, such as Requirements, Source, or Language. We will also, of course, consider any suggestion we will receive from you, the user.